Tech Arsenal 1/Tech Arsenal (Arsenal Computer).ISO/tek-01/wcomm111.zip/WARPCOMM.DOC

Text File | 1991-02-03 | 18KB | 654 lines

                    The Warp Communications Library

                              Version 1.11

                                written

                                   by

                              Trevor Bell

                Copyright (C) 1991, All Rights Reserved.


WHAT IT IS:

        The Warp Communications Library is a full-featured modem/serial
communications library.  It can be used to create BBS doors, protocols,
terminal programs, or actual BBS programs.  Currently the library only
supports Turbo C and Turbo C++ with libraries for each, however support
for MSC is on the way and if you are a registered user with the source
code then you could easily modify the source to work with any C
compiler.  Warp Comm supports baud rates of up to 57,600.  Warp Comm
currently supports up to 8 com ports open in simultaneous operation
however, this could be increased to almost any value with the source code.

        Warp Comm is NOT PUBLIC DOMAIN, Warp Comm IS SHAREWARE.  A
registration fee of $25 (of course I won't mind if you send more than
$25) is required if you wish to use Warp Comm in any application to be
distributed to the general public.  Registration will get you the full
source code for both the Turbo C and Turbo C++ libraries and library files
for each of 5 memory models (small, medium, compact, large, huge).
Without registration you will be limited to compiling programs in the small
memory model and this will substantially limit programs.  By registering
this program you will be contributing to the release of future versions
of Warp Comm and future programs that I will be creating.  Your
registration will be greatly appreciated.  See the file ORDER.FRM for
details on registering.

Registrations may be sent to:

        Trevor Bell
        P.O. Box 4173
        Redondo Beach, CA  90278

I can be contacted on THE SOURCE BBS at 213-371-3737.
I can also be reached at fidonet node 1:102/134.


Two zip files are provided, one for Turbo C and Turbo C++ in standard
C mode and one for Turbo C++ only in C++ mode.  They are:

TC.ZIP  (For C only)
TCP.ZIP (For C++ only)



HOW TO USE IT:

--------------------------------------------------------------------------------

               For Turbo C++ and Turbo C users in Standard C mode

--------------------------------------------------------------------------------

The file WARPCOMM.H must be included in any program wishing to use the
Warp Comm library in TC, and the library file WCOMMS.LIB must be linked with
the program.


Opening the Com Port:
---------------------

void com_open (unsigned int port, unsigned int baud_rate,
        unsigned int interrupt_request,
        unsigned int base_address, unsigned int receive_buffer_size,
        unsigned int transmit_buffer_size);

port - which com port to open

baud_rate - the baud rate to open the com port at

interrupt request - which IRQ to open the comport at, usual values are
        as follows:

        COM port 1: IRQ 4
        COM port 2: IRQ 3

        all other COM ports are non-standard and would be machine
        dependent.

base_address - which base address to use, common values are as follow:

        COM port 1: 0x3f8 (Hex)
        COM port 2: 0x2f8 (Hex)

receive buffer size - this can vary with modem speed and the application
        being used however, 2000 characters is usually a good place to start.

transmit buffer size - this can vary with modem speed and the application
        being used however, 2000 characters is usually a good place to start.

Thus opening COM 1 at 2400 baud would work like this:

        com_open(2400, 4, 0x3F8, 2000, 2000);


Outputting to the Com Port:
---------------------------

void com_out_char(unsigned int port, char value);

Outputting to the comport in TC is accomplished like this:

char value = 13;
com_out_char(0, value);


Inputting from the Com Port:
----------------------------

void com_get_char(unsigned int port);

Inputting from the comport in TC is accomplished like this:

char value;
value=com_get_char(0);


Checking for a character waiting to be read:
--------------------------------------------

void char_waiting(unsigned int port);

Often it is necessary to know if there is a character waiting in the com
port receive buffer, this can be checked with the char_waiting function
which returns a 1 if there is a character or characters waiting, and a 0
if the com port buffer is empty.  It is used like this:

char value;

if( char_waiting(0)) {
    value=com_get_char(0);
}


Closing the Com Port:
---------------------

void com_close(unsigned int port);

Closing out the com port is a simple task, it will disable com port
interrupt routine, and free the memory allocated by the transmit and receive
buffers.  It is used like this:

com_close(0);


Sending a string to the Com Port:
---------------------------------

void com_out_char_str(unsigned int port, char *string);
void send_modem_string(unsigned int port, char *string);

A null terminated string can be sent to the com port like this:

char *string="This is a null-terminated string.";
com_out_char_str(0, string);

an alternate method of sending strings to the modem can also be used,
like this:

send_modem_string(0, "ATZ|");

where the | command represents a carriage return.



Sending a buffer to the Com Port:
---------------------------------

void com_out_buf(unsigned int port, unsigned char *buffer, unsigned int length);

A buffer of a specified size can be sent to the com port like this:

unsigned char *buffer;
unsigned int length=10;
com_out_buf(0, buffer,length);


Receiving a buffer from the Com Port:
-------------------------------------

void com_get_buf(unsigned int port, unsigned char *buffer, unsigned int length);

A buffer of a specified size can be received from the com port like this:

unsigned char *buffer;
unsigned int length=10;
com_get_buf(0, buffer,length);


Setting the DTR pin of the modem:
---------------------------------

void set_dtr(unsigned int port, unsigned int value);

The DTR pin of the modem can be changed like this:

set_dtr(0, 1);

A value of 1 will hold the DTR high, a value of 0 will hold it low
causing most modems to hangup.


Setting the RTS pin of the modem:
---------------------------------

void set_rts(unsigned int port, unsigned int value);

The RTS pin of the modem can be changed like this:

set_rts(0, 1);

A value of 1 will hold the RTS high allowing some modems to use hardware
flow control (consult your modem manual on this), a value of 0 will
hold it low.


Clearing the transmit or receive buffers:
-----------------------------------------

void clear_xmit_buffer(unsigned int port);

Clearing the transmit buffer will clear any characters waiting to be
sent to the com port and is accomplished like this:

clear_xmit_buffer(0);

Clearing the receive buffer will clear any characters waiting to be
received the com port and is accomplished like this:

clear_receive_buffer(0);


Changing the baud rate:
-----------------------

void set_baudrate(unsigned int port, unsigned int baud_rate);

Changing the baud rate on the modem is accomplished like this:

set_baudrate(0, 2400);


Detecting a Carrier:
--------------------

The carrier detect pin of the modem can be checked by examining the
integer variable CD.  If CD is 1 then a carrier is present, if CD is 0
then no carrier is present.  It can be used like this:

if(remote[0].CD==1) {
    puts("A carrier is detected.");
}

Reading the interrupt enable register:
--------------------------------------

unsigned char read_ier(unsigned int port);

The interrupt enable register can be read like this:

unsigned char value;
value=read_ier(0);


Reading the line status register:
--------------------------------------

unsigned char read_lsr(unsigned int port);

The line status register can be read like this:

unsigned char value;
value=read_lsr(0);


Reading the modem status register:
--------------------------------------

unsigned char read_msr(unsigned int port);

The modem status register can be read like this:

unsigned char value;
value=read_msr(0);


Reading the line control register:
--------------------------------------

unsigned char read_lcr(unsigned int port);

The line control register can be read like this:

unsigned char value;
value=read_lcr(0);


Reading the modem control register:
--------------------------------------

unsigned char read_mcr(unsigned int port);

The modem control register can be read like this:

unsigned char value;
value=read_mcr(0);



--------------------------------------------------------------------------------

                      Turbo C++ users in C++ mode

--------------------------------------------------------------------------------

The file WARPCOMM.HPP must be included in any program wishing to use the
Warp Comm library in TC++, and the library file WCOMMS.LIB must be linked with
the program.  In the Turbo C++ versions of the library all the commands
and most of the data structures are contained within the COM_port class,
and thus must be accessed through the variable remote which is defined
like this:

COM_port remote[8];

Opening the Com Port:
---------------------

void open (unsigned int port, unsigned int baud_rate,
        unsigned int interrupt_request, unsigned int base_address,
        unsigned int receive_buffer_size, unsigned int transmit_buffer_size);

port - this is the com port you are opening, this number should match
       the array element of remote you are using

baud_rate - the baud rate to open the com port at

interrupt request - which IRQ to open the comport at, usual values are
        as follows:

        COM port 1: IRQ 4
        COM port 2: IRQ 3

        all other COM ports are non-standard and would be machine
        dependent.

base_address - which base address to use, common values are as follow:

        COM port 1: 0x3f8 (Hex)
        COM port 2: 0x2f8 (Hex)

receive buffer size - this can vary with modem speed and the application
        being used however, 2000 characters is usually a good place to start.

transmit buffer size - this can vary with modem speed and the application
        being used however, 2000 characters is usually a good place to start.

Thus opening COM 1 at 2400 baud with an IRQ of 4 and with 2000 byte receive
and transmit buffers would work like this:

        remote[0].open(0, 2400, 4, 0x3F8, 2000, 2000);


Outputting to the Com Port:
---------------------------

Outputting to the comport in TC++ is identical to file stream output in C++,
you simply use the overloaded bitshift operator with the variable to
output to the port, like this:

char value = 13;
remote[0] << value;


Inputting from the Com Port:
----------------------------

Inputting from the comport in TC++ is identical to file stream input in C++,
you simply use the overloaded bitshift operator with the variable to
input from the port, like this:

char value;
remote[0] >> value;


Checking for a character waiting to be read:
--------------------------------------------

Often it is necessary to know if there is a character waiting in the com
port receive buffer, this can be checked with the char_waiting function
which returns a 1 if there is a character or characters waiting, and a 0
if the com port buffer is empty.  It is used like this:

char value;

if( remote[0].char_waiting()) {
    remote[0] >> value;
}


Closing the Com Port:
---------------------

void close(void);

Closing out the com port is a simple task, it will disable com port
interrupt routine, and free the memory allocated by the transmit and receive
buffers.  It is used like this:

remote[0].close();


Sending a string to the Com Port:
---------------------------------

void send_modem_string(char *s);

A null terminated string can be sent to the com port like this:

char *string="This is a null-terminated string.";
remote[0] << string;

an alternate method of sending strings to the modem can also be used,
like this:

remote[0].send_modem_string("ATZ|");

where the | command represents a carriage return.


Sending a buffer to the Com Port:
---------------------------------

void out_buf(unsigned char *buffer, unsigned int length);

A buffer of a specified size can be sent to the com port like this:

unsigned char *buffer;
unsigned int length=10;
remote[0].out_buf(buffer,length);


Receiving a buffer from the Com Port:
-------------------------------------

void get_buf(unsigned char *buffer, unsigned int length);

A buffer of a specified size can be received from the com port like this:

unsigned char *buffer;
unsigned int length=10;
remote[0].get_buf(buffer,length);


Setting the DTR pin of the modem:
---------------------------------

void set_dtr(unsigned int value);

The DTR pin of the modem can be changed like this:

remote[0].set_dtr(1);

A value of 1 will hold the DTR high, a value of 0 will hold it low
causing most modems to hangup.


Setting the RTS pin of the modem:
---------------------------------

void set_rtr(unsigned int value);

The RTS pin of the modem can be changed like this:

remote[0].set_rts(1);

A value of 1 will hold the RTS high allowing some modems to use hardware
flow control (consult your modem manual on this), a value of 0 will
hold it low.


Clearing the transmit or receive buffers:
-----------------------------------------

void clear_xmit_buffer(void);
void clear_receive_buffer(void);

Clearing the transmit buffer will clear any characters waiting to be
sent to the com port and is accomplished like this:

remote[0].clear_xmit_buffer();

Clearing the receive buffer will clear any characters waiting to be
received the com port and is accomplished like this:

remote[0].clear_receive_buffer();


Changing the baud rate:
-----------------------

void set_baudrate(unsigned int baud_rate);

Changing the baud rate on the modem is accomplished like this:

remote[0].set_baudrate(2400);


Detecting a Carrier:
--------------------

The carrier detect pin of the modem can be checked by examining the
integer variable CD.  If CD is 1 then a carrier is present, if CD is 0
then no carrier is present.  It can be used like this:

if(remote[0].CD==1) {
    puts("A carrier is detected.");
}


Reading the interrupt enable register:
--------------------------------------

unsigned char read_ier(void);

The interrupt enable register can be read like this:

unsigned char value;
value=remote[0].read_ier();


Reading the line status register:
--------------------------------------

unsigned char read_lsr(void);

The line status register can be read like this:

unsigned char value;
value=remote[0].read_lsr();


Reading the modem status register:
--------------------------------------

unsigned char read_msr(void);

The modem status register can be read like this:

unsigned char value;
value=remote[0].read_msr();


Reading the line control register:
--------------------------------------

unsigned char read_lcr(void);

The line control register can be read like this:

unsigned char value;
value=remote[0].read_lcr();


Reading the modem control register:
--------------------------------------

unsigned char read_mcr(void);

The modem control register can be read like this:

unsigned char value;
value=remote[0].read_mcr();



--------------------------------------------------------------------------------

                             CODE EXAMPLES

--------------------------------------------------------------------------------


A very simple terminal program is provided with Warp Comm to demonstrate
it's capabilities very minimally.  Feel free to modify it to your
heart's desire, keep in mind however that without registration your
program will need to remain within the small memory model.

The source code for this program is provided in the file TERM.C or
TERM.CPP for TC and TC++ respectively.



--------------------------------------------------------------------------------

                                SUPPORT

--------------------------------------------------------------------------------


Support can be obtained through mail sent to my P.O. Box or by calling the
following BBS:

        Name:           The Source
        SysOp:          Chip North
        BBS Software:   Wildcat
        Phone #:        [phone]

I can also be reached at fidonet node 1:102/134.

--------------------------------------------------------------------------------

                            VERSION HISTORY

--------------------------------------------------------------------------------


Version 1.00:
        not released to the public

Version 1.01:
        My first release!

Version 1.02:
        Fixed null pointer assignment.

Version 1.03:
        Fixed some other minor bugs.

Version 1.04:
        Sped up the interrupt service routine a bit.

Version 1.10:
        Multi-Line Support added!!!
        Added functions to read all of the important UART ports.
        Rewrote almost all functions to add multi-com port support and
        better optimization.

Version 1.11:
        Maintenance release - included the outstr.obj file to the library
        which should have been there since the beginning.